The following macros provide a standard, architecture-independent
means for calculating page-size dependent values:
o $BYTES_TO_PAGES
o $NEXT_PAGE
o $PAGES_TO_BYTES
o $PREVIOUS_PAGE
o $ROUND_RETADR
o $START_OF_PAGE
These macros reside in the directory SYS$LIBRARY:STARLET.MLB and
can be used by both application code and system code. Because
application code does not have access to SYSTEM_DATA_CELLS, you
must supply the relevant masks, shift values, and so on.
The shift values are correlated with the page size of the
processor. The rightshift values are negative; the leftshift
values are positive, as shown in Shift Values.
Table D-1 Shift Values
Page size rightshift leftshift
512 bytes (VAX) -9 9
8K (OpenVMS Alpha or -13 13
OpenVMS I64)
16K -14 14
32K -15 15
64K -16 16
Typically, the application issues a call to $GETSYI (specifying
the SYI$_PAGESIZE item descriptor) to obtain the CPU-specific
page size and then compute other values from the page size that
is returned.
The following conventions apply to the macros described in this
section:
o If the destination operand is blank, the source operand is
used as the destination.
o All macros conditionalize code on the symbols VAXPAGE and
BIGPAGE.
o Several macros allow for page-size-independent code on VAX
systems with the independent=YES argument. These macros
generate code in which I-stream fetches are changed to memory
accesses. Because this is inherently slower on a VAX system,
the default value of the independent argument is NO.
1 – $BYTES TO PAGES
Converts a byte count to a page count.
Format
$BYTES_TO_PAGES source_bytcnt, dest_pagcnt, rightshift,
roundup=YES, quad=YES
1.1 – Parameters
source_bytcnt
Source byte count.
dest_pagcnt
Destination of page count.
rightshift
Location of application-provided value to shift (in place of
multiply). This value is a function of the page size, as shown in
the table on shift values.
roundup=YES
If YES, page-size-1 is added to byte count before shifting;
if NO, page count is truncated. Any other value is treated as
the user-specified address of the page-size-1 value. Note that
roundup=YES is incompatible with the presence of the rightshift
argument; invoking the macro with both these arguments generates
a compile-time warning.
quad=YES
If YES, the conversion supports 64-bit addressing. If NO, the
conversion does not support 64-bit addressing.
2 – $NEXT PAGE
Computes the virtual address of the first byte in the next page.
Format
$NEXT_PAGE source_va, dest_va, clearbwp=NO,
user_pagesize_addr, user_mask_addr, quad=YES
2.1 – Parameters
source_va
Source virtual address.
dest_va
Destination of virtual address within next page.
clearbwp=NO
If YES, masks the byte-within-page portion of the source virtual
address. The clearbwp=NO option is a performance enhancement,
avoiding unnecessary instructions if you know you are starting
on a page boundary or you are intending to divide by page-size
anyway.
user_pagesize_addr
Location of the page-size value (returned by a call to the
$GETSYI system service specifying the SYI$_PAGESIZE item
descriptor) in the application data area. If this argument is
blank, the macro uses MMG$GL_PAGESIZE (bigpage) or MMG$C_VAX_
PAGE_SIZE (vaxpage).
user_mask_addr
Location of the application-provided byte-within-page mask. If
this argument is blank, the macro uses MMG$GL_BWP_MASK if user_
pagesize_addr is also blank. Otherwise, it subtracts 1 from the
contents of the user_pagesize_addr and uses that value.
quad=YES
If YES, the conversion supports 64-bit addressing. If NO, the
conversion does not support 64-bit addressing.
3 – $PAGES TO BYTES
Converts a page count to a byte count.
Format
$PAGES_TO_BYTES source_pagcnt, dest_bytcnt, leftshift,
quad=YES
3.1 – Parameters
source_pagcnt
Source page count.
dest_bytcnt
Destination of byte count.
leftshift
Location of application-provided value to shift (in place of
multiply). This value is a function of the page size, as shown in
the table on shift values.
quad=YES
If YES, the conversion supports 64-bit addressing. If NO, the
conversion does not support 64-bit addressing.
4 – $PREVIOUS PAGE
Computes the virtual address of the first byte in the previous
page.
Format
$PREVIOUS_PAGE source_va, dest_va, clearbwp=NO,
user_pagesize_addr, user_mask_addr,
quad=YES
4.1 – Parameters
source_va
Source virtual address.
dest_va
Destination of virtual address within previous page.
clearbwp=NO
If YES, masks the byte-within-page portion of the source virtual
address. The clearbwp=NO option is a performance enhancement,
avoiding unnecessary instructions if you know you are starting
on a page boundary or you are intending to divide by page-size
anyway.
user_pagesize_addr
Location of the page-size value (returned by a call to the
$GETSYI system service specifying the SYI$_PAGESIZE item
descriptor) in the application data area. If this argument is
blank, the macro uses MMG$GL_PAGESIZE (bigpage) or MMG$C_VAX_
PAGE_SIZE (vaxpage).
user_mask_addr
Location of the application-provided byte-within-page mask. If
this argument is blank, the macro uses MMG$GL_BWP_MASK if user_
pagesize_addr is also blank. Otherwise, it subtracts 1 from the
contents of the user_pagesize_addr and uses that value.
quad=YES
If YES, the conversion supports 64-bit addressing. If NO, the
conversion does not support 64-bit addressing.
5 – $ROUND RETADR
Rounds the range implied by the virtual addresses in a retadr
array returned from a memory management system service to a range
that is the factor of CPU-specific pages. The return value can be
supplied as an inadr array in a subsequent call to another memory
management system service.
Format
$ROUND_RETADR retadr, full_range, user_mask_addr,
direction=ASCENDING
5.1 – Parameters
retadr
Address of array of two 32-bit addresses, typically returned from
$CRMPSC or a similar service. This value can be in the form of
either "label" or "(Rx)".
full_range
Output array of two longwords. FULL_RANGE[0] is retadr[0]
rounded down to a CPU-specific page boundary, and FULL_RANGE[1]
is retadr[1] rounded up to one less than a CPU-specific page
boundary (that is, to the last byte in the page).
user_mask_addr
Location of application-provided byte-within-page mask. If this
argument is blank, the macro uses MMG$GL_BWP_MASK on an OpenVMS
Alpha or OpenVMS I64 system and VA$M_BYTE on an OpenVMS VAX
system.
direction=ASCENDING
Direction of rounding. The keywords are defined in the following
table:
ASCENDING retadr[0] < retadr[1]
DESCENDING retadr[1] < retadr[0]
UNKNOWN Values are compared at run time, then proper
rounding is performed
6 – $START OF PAGE
Converts a virtual address to the address of the first byte
within that page.
Format
$START_OF_PAGE source_va, dest_va, user_mask_addr, quad=YES
6.1 – Parameters
source_va
Source virtual address.
dest_va
Destination of virtual address of first byte within page.
user_mask_addr
Location of application-provided byte-within-page mask. If this
argument is blank, the macro uses MMG$GL_BWP_MASK on an OpenVMS
Alpha or OpenVMS I64 system and MMG$C_VAX_PAGE_SIZE - 1 (defined
in $pagedef) on an OpenVMS VAX system.
quad=YES
If YES, the conversion supports 64-bit addressing. If NO, the
conversion does not support 64-bit addressing.